Repository navigation
Workbench foundations, query IDE, chat and a macOS test build - #1
Merged
Merged
Conversation
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The engine MCP server writes stackql_mcp_server_*.log into its working directory, so those are ignored wherever they land. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Product name StackQL Workbench, binary stackql-workbench, identifier io.stackql.workbench. Lint, format, typecheck and test wiring for the webview and the host. Dependencies beyond the stack table, with reasons: serde, serde_json and thiserror for typed IPC payloads and errors; futures-util to consume the pg wire row stream; windows-sys (Windows only) for the job object that ties engine processes to the app; vitest and jsdom for webview tests; eslint, typescript-eslint, eslint-plugin-react-hooks, eslint-config-prettier and prettier for the lint and format checks. TypeScript is pinned to 6.0.x because typescript-eslint does not support 7 yet. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Adds the probe program and the findings. Simple protocol only, one statement per message, text values, no cancel, upstream failures surface as notices only with --pgsrv.debug.enable. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Discovery follows the documented resolution order and treats an explicit but wrong path as an error. The supervisor captures stderr and ties every child to the app: a kill-on-close job object on Windows, a process group plus a pipe watchdog on Unix. A test kills a stand-in app process and checks its child is gone. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
LocalConnection is the only Connection. It starts stackql srv on loopback with an explicit approot and --pgsrv.debug.enable, waits for SHOW VERSION, and watches for an unexpected exit. The query service uses the simple protocol, splits text into statements because srv runs only the first one in a message, counts rows itself, and reports only new notice text on the long-lived editor session. Explorer statements are built from validated, double-quoted identifiers. Integration tests run against a real engine with the built-in provider only, and are skipped when no binary is found. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Three panes and a status bar over the typed host wrapper in src/host, the only module that imports Tauri. The explorer is a lazy tree built from metadata statements. The editor is one CodeMirror buffer with a StackQL dialect, and Ctrl+Enter or Cmd+Enter runs the selection or the whole buffer. The grid is virtualised, with a cell viewer that pretty-prints JSON and a messages tab for notices, errors and engine output. A launcher runs Vitest from an upper-case drive letter, because Vitest fails on Windows when the working directory is spelled with a lower-case one. Adds @lezer/highlight as a direct dependency for the highlight tags used by the editor theme. It was already installed as part of CodeMirror. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Copying a name goes through a write-only host command built on arboard (text only, default features off), so it does not depend on webview focus or on how the platform webview treats the app origin. The CI workflow runs format, lint, typecheck, tests and a debug build on windows-latest and macos-latest, with stackql installed so the integration tests are not skipped. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Running the supervisor tests on Linux showed the watchdog never signalled the process group: dash rejects 'kill -TERM -- -PGID'. The script now uses 'kill -s TERM -- -PGID', which dash and bash both accept. All supervisor and watchdog tests pass on Linux, including killing the parent with SIGKILL. CLAUDE.md now reflects what M0 built: status, stack additions and version constraints, the real layout, the commands, and the srv behaviour found by the spike. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Provider nodes show the provider's own icon, resolved through the provider dictionary published by stackql.io. The host fetches and caches icons and hands them to the webview as data URLs, so the webview still makes no network calls. Icon paths from the dictionary are checked before use and only the dictionary host and stackql.io are contacted. A provider that cannot be resolved keeps the letter badge. The app icon is now StackQL's favicon, generated from the 512px version in the stackql.io repository. New dependencies: reqwest for HTTPS, with native-tls so the OS TLS stack and trust store are used and no extra build tools are needed on Windows; base64 for data URLs. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
stackql_preview and any other stackql_* provider are part of the engine and are not in the published dictionary. They now show StackQL's own icon, compiled in, instead of the letter badge. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The previous commit introduced a method named from_dictionary that takes self, which clippy rejects. No behaviour change. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ckends The host runs the agent loop and owns the MCP client. The Connection trait gains the agent channel: LocalConnection starts stackql mcp over stdio through the supervisor, in the workspace safety mode, with its audit log under the app data directory. The engine classifies and gates statements. The host relays its approval prompts to the operator and never answers one itself. InferenceBackend sits between the loop and a model. Backends: Gemini (generateContent), Anthropic (Messages API) and OpenAI-compatible (Chat Completions, which covers local inference). Each keeps the provider's reply and returns it untouched, so thought signatures and thinking blocks survive. API keys are read from the OS keychain and never reach settings, logs or the webview. Upstream API failures reach the model as an empty result, so the host watches the MCP server's stderr during each tool call and adds a note for the model and the operator. Tested without any API key: the backends against a local stub that records the request, and the loop against a real stackql mcp with a scripted model, covering tool calls, approval, decline, read_only refusal, stop and the audit log. New dependencies: rmcp (the official Rust MCP SDK, client and async-rw transport only), keyring-core with windows-native-keyring-store and apple-native-keyring-store for the OS keychain. docs/spike-mcp.md records the MCP findings. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The chat pane shows each tool call the assistant makes, with the statement as SQL that can be opened in the editor. Row results appear in the same grid as editor results, marked as coming from the assistant. An approval prompt from the engine becomes a card showing the exact SQL, and nothing runs until the operator decides. The activity pane merges the operator's statement history with the engine's agent audit log. Chat settings choose the backend, model and address and send the key to the OS keychain. With no backend the chat pane is hidden and the rest of the app is unchanged. Verified in the running app against a local stand-in model: tool call, grid result, decline, approve, upstream failure note and the audit trail. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md and README.md now describe what exists: status and what has and has not been run, the real layout, the MCP server behaviour from the spike, the three backends and how they are built, and the engine-side questions the spikes raised. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…move it The engine's --approot was fixed at <app data dir>/engine. It is now resolved at each engine start, first hit wins: 1. the folder named in settings (new "Engine data folder" field) 2. .stackql beside the Workbench executable 3. <app data dir>/engine The folder in settings is strict: a relative path, or one that cannot be created or written to, stops the engine with a message that points at Settings. The folder beside the executable falls through to the app data folder when it cannot be written to, which is what happens for an app installed under Program Files, and is skipped inside a macOS app bundle because writing there breaks the bundle's signature. The settings pane shows the folder in use, how it was chosen and the reason for a fallback. The MCP server is started on the same folder as the running engine. The audit log and statement history stay under the app data directory. No new dependencies. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A method used to open into one flat list: required inputs, optional inputs, then outputs. It now opens into two groups, Inputs and Outputs, both collapsed until opened. Each group shows a count, and Inputs also says how many are required. A group with nothing in it cannot be opened and says "none". The fields still come from one DESCRIBE METHOD EXTENDED. The groups carry their members, so opening one makes no second request. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…s own On Windows every child was put in one kill-on-close job. A process that starts out in a job of its own cannot join a job that already has members, and AssignProcessToJobObject fails with access denied. A packaged app starts that way, and a program on PATH can be an app execution alias for one. The GitHub Copilot CLI installed through the Windows package manager is such an alias, and could not be started. When the shared job will not take a child, the supervisor now creates an empty kill-on-close job for that child alone, which the OS always allows, and holds it for as long as the child runs. The rule is the same: the process tree dies when the app's handle closes, whatever ends the app. Closing the job when the child is stopped also ends anything the child left running. A test at the job level pins the OS rule this depends on. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Adds the first delegated agent: chat can run through the GitHub Copilot CLI the operator already has installed and signed in to. The CLI runs the model and is the MCP client. The host starts it under the supervisor, drives it over the Agent Client Protocol, and shows what it does. The host never sees or handles the CLI's sign-in. What the host does, each point tested against Copilot CLI 1.0.113 and recorded in docs/spike-acp.md: - starts `copilot --acp` and speaks ACP version 1 over stdio - names the engine's MCP server in a file passed with --additional-mcp-config, as `stackql`, because the CLI rejects a stdio server passed in session/new and then silently falls back to the operator's own configuration - passes --available-tools with the engine's tool names, read from the engine, so the model has no shell, no file access and no other MCP server, and --allow-tool=stackql so the CLI does not prompt for each engine tool call - passes the workspace safety mode to the engine as for other backends - declines any session/request_permission and tells the operator - sets the model with session/set_config_option when one is chosen, and can list the models with their usage multipliers without sending a prompt The CLI does not relay MCP elicitation, so on this path the engine refuses a statement that needs approval instead of asking. It fails closed. The host puts no gate of its own in that place. Shape of the change: - agent/acp.rs: a small ACP client, JSON-RPC over a byte stream - agent/delegate.rs: a session with an agent, and the mapping from its updates to the chat events the webview already understands - agent/copilot.rs: the Copilot command line and how it is found - Connection::open_delegate_channel: the connection starts the agent and tells it how to start the MCP server in a safety mode, so the runtime still never spawns a process - new events: DelegateStarted, and AssistantDelta for text that arrives in pieces - BackendKind::GithubCopilot, which has no key in the keychain No new dependencies. The ACP client is written here because the part needed is five methods, and every behaviour that matters was observed against the real agent. CLAUDE.md and README.md record the decision. They also describe the chat-first layout, which lands in the next commit. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…lies Chat is now the view the app opens in, in place of a side pane beside the query IDE. - A side menu leads to New Chat, the explorer (provider tree, editor and results) and activity, lists the current conversation under Chats, and has Settings at the bottom. It can be collapsed to icons. - File, Edit and View menus repeat what the side menu and panes offer, with shortcuts: Ctrl+N new chat, Ctrl+1/2/3 for the views, Ctrl+B for the side menu, Ctrl+, for settings. They are drawn in the webview, so they are the same on both platforms and testable like the rest of the page. - Sending a message with no model backend opens the model backend settings and keeps what was typed. Saving a backend there returns to the conversation. This replaces "chat is hidden until configured". - The composer shows the backend and model, and the safety mode with what it means for the backend in use. - Row results from the assistant are shown in the conversation, first rows only, with "Open in grid" for the full result. - Replies are read as markdown: headings, lists, tables, emphasis, inline code. The reader builds a tree and never HTML, leaves snake_case names and SQL stars alone, and shows links without opening them. - Text from a delegated agent appears as it is written. - Model backend settings gain GitHub Copilot: an optional CLI location, a button that asks the CLI for its models, and a list that shows what a request to each costs against the plan. - Every view stays mounted while another is shown, so the editor keeps its text and history and a running turn keeps its place. The window close permission is added for File > Exit. Closing the window ends the app the usual way, which stops the engine. No new dependencies. The markdown reader is about 250 lines with tests, which was preferred over a library for output that comes from a model. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The Inputs and Outputs groups split a method's fields on the engine's param type. Only `output` was treated as an output, and everything else as an input. The provider built into the engine marks what a method returns as `response`, so those fields were listed under Inputs. A field is now an input when its param type starts with `input`, and an output otherwise. Found while checking the grouping in the release build against the built-in provider. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… mode The file that tells the Copilot CLI how to start the engine's MCP server was written to one fixed path. Two instances of the app in different safety modes could then overwrite it between one writing it and its CLI reading it, and an agent could start in the other instance's mode. The file name now includes the mode. Its content depends on nothing else that differs between instances sharing a data folder. Found while running two instances side by side for the force-kill check. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…e tree The explorer no longer lists stackql_preview, the provider built into the engine. It is hidden for now and may come back. The name is in HIDDEN_PROVIDERS in query/explorer.rs and nowhere else, so removing it there brings the provider back. Only the tree leaves it out. SHOW PROVIDERS in the editor still shows what the engine says, and what the engine tells a model is not filtered. An engine with nothing installed now gives an empty tree with the hint about REGISTRY PULL, where it used to show the built-in provider above that hint. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ow to read an empty result Decided by the maintainer: the engine's answer to a provider call that returned nothing stays an empty, successful result on both channels. A lookup of one thing that does not exist is an ordinary question, and "not found" is its answer. The engine also reaches providers over more than one protocol, so nothing may sort a provider's answer by HTTP status code. The host and the UI had been wording this as a failure. They now pass the provider's message on and do not rule on it: - the results pane and the tool card say that nothing may have matched, or that the call may not have succeeded - the note the host adds to a tool result for the model says the same - looksLikeUpstreamFailure is now emptyWithNotice For a model the fix is instructions, not an error. One text, empty_result_guidance!, is used for both the host's loop and a delegated agent. It says what an empty result does and does not show, to check that the provider is answering before reporting that it has none of something or acting on something being absent, and that an empty result is never proof that a change happened. It names no protocol and no status code, and a test holds it to that. CLAUDE.md records the decision under Empty results and takes the item off the open questions. The two spike reports keep their findings and note that their first suggestion, an error result, was decided against. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The previous commit added guidance for a model on reading empty results,
on top of a note the host had been appending to a tool result since the
chat milestone. Both rested on a finding that was wrong: that the
engine's MCP server hides provider failures from the model.
It does not. Checked against v1.0.888 with no provider credentials:
- a call that needs a sign-in comes back as a tool error,
upstream http error: {"http_status": 401, "retryable": false}: ...
- a list for an owner that does not exist comes back as no rows, which is
the intended answer to a lookup that finds nothing
The engine source says the same. Its MCP backend runs statements with
strict upstream errors and classifies them, and its instructions tell a
model how to read errors and empty results. The first finding came from
testing one lookup that found nothing and taking it for every failure.
The maintainer's direction is that this belongs in the engine's MCP
server and not here. So:
- the model guidance on empty results is removed from both prompts
- the host no longer adds a note to what the model receives. The model
gets the server's rendering and nothing else
- the stderr line with what a provider answered is still shown to the
operator beside the tool result, as a plain message and not a warning
CLAUDE.md states where this is handled and that no logic for it goes in
this app. The spike reports carry a dated correction with the second test
case, and no longer ask the engine for something it already does.
Nothing was changed in the stackql repository.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Measured against v1.0.888 with default flags: four independent single-request statements sent together were answered in about the time of one, in two runs of three. The third had one late answer that was not explained. Recorded because it decides whether sending independent statements together is worth doing. The host's loop does not do it yet. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…time With an API key backend the host ran the tool calls of a model reply one after another, even when the model asked for several independent queries in one go. One stackql MCP server runs calls at the same time, so that was time spent waiting for nothing. The calls of one reply now run together when the engine marks the tool as not destructive. The engine publishes that on every tool as destructiveHint: its query and discovery tools say false, and run_mutation_query and run_lifecycle_operation say true. A tool marked destructive, or one with no hint, or one the server does not have, runs alone and in the model's order, so what follows a change sees the change. The host takes the engine's word for this and reads nothing into the statement. Results go back to the model in the order it asked. What had to change with it: - stopping a turn now reaches every call that is waiting, not one of them - an approval prompt is shown on the tool call that sent the statement, matched by statement and tool, since more than one call can be running and more than one prompt can be open - what a provider answered is read from the server's stderr, which cannot say which call a line belongs to. When calls overlap it is shown for none of them Two integration tests against the real engine cover it: three independent calls are all under way before the first finishes and answer in order, and a mutation between two queries waits for the first and holds up the second. No new dependencies. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…agents The Copilot CLI can hand part of a task to a subagent, through its task tool. The backend had turned that off along with everything else that is not an engine tool. It is now allowed, as a setting that is on by default. Tested before building, with two prompts, and recorded in docs/spike-acp.md: - adding task to --available-tools brings back that tool and nothing else. A subagent asked to run a shell command and to write a file had no tool for either, raised no permission request and wrote nothing - subagents use the same MCP server as the main agent, so the same engine and the same safety mode - a subagent's tool calls and messages carry its id, and the CLI will name the subagent in an event when asked at the handshake - two subagents started in one step ran at the same time - a subagent can start subagents. The CLI stops that at depth four What the host does: - adds task to the tool list when the setting is on - tells the agent in the first prompt when to use subagents: independent lookups across providers, services or resources, never a change, and no more than four at once - shows the start of a subagent with its task, not its whole prompt, and marks each tool call with the subagent that made it - keeps a subagent's own message text out of the conversation, since it arrives whole as the result of the call that started the subagent - stops a turn that starts more than 12 subagents, and says why The direction on when to split work is in this app and not in the engine's instructions, because starting agents is the client's capability. Not measured: what subagents cost. The CLI picks their model, gpt-6-luna when tested, and will not write usage in ACP mode. No new dependencies. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…work A real turn through the app showed the first version was not enough. Left to choose, the model started subagents of the explore kind in background mode. That kind has none of the engine's tools, and a background subagent has to be read back with a tool the agent does not have under this tool list. The subagents did nothing, the main agent did the lookups itself, and the answer was right for the wrong reason. The CLI has three kinds of subagent. Each was asked to run a shell command, write a file and call an engine tool: general-purpose no shell, no file write, engine tools, session's model task no shell, no file write, engine tools, gpt-6-luna explore no shell, no file write, no engine tools, gpt-6-luna So the restriction to the engine holds for every kind, and two of them are of use. The guidance on subagents now ends with advice from the agent's profile: general-purpose, sync mode, started in one step so they run together, and not the explore kind or background mode. The advice is in the Copilot profile because it is about the Copilot CLI's task tool. docs/spike-acp.md has the table and what happened in the turn that showed the problem. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ests A second real turn through the app showed that allowing subagents is safe and not yet dependable. Asked a question that spans two providers, with no mention of subagents, the model did the two lookups itself and got a large result. The CLI keeps a large tool result in a temporary file for the model to read, and the model has no tool that reads files here. It then started a subagent to count the result. That one could not read the file either and started another, four deep, twice. Ten subagents ran, the turn took 108 seconds and the count was wrong. The same question had earlier been answered correctly in 27 seconds. So what the model used subagents for was not the dividing of independent work. It was a way out when stuck, and a stuck model costs more with the task tool to hand than without it. That was claude-haiku-4.5. A larger model was not tried. Changes: - subagents are off unless the operator turns them on, and the setting is marked experimental and says why - a turn is stopped at the first subagent that starts a subagent of its own, with a notice. In every run where that happened, the subagent had been unable to do its job - the cap of 12 subagents in a turn stays docs/spike-acp.md records the turn. CLAUDE.md says not to turn subagents on by default without testing this again. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The wordmark in the side menu was 13 px tall and easy to miss. It is 20 px tall now, 131 px wide, and its row is a little taller to hold it. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A second job builds the app for macOS and keeps the disk image as the workflow artifact stackql-workbench-macos-universal, so the app can be tried on a Mac before there is any packaging. - The build is universal, for Apple Silicon and Intel, so it does not matter which Mac the tester has. - The signature is ad hoc, set with APPLE_SIGNING_IDENTITY for that step only. An Apple Silicon Mac runs no code without a signature. Nothing is notarised, and tauri.conf.json is unchanged, so this decides nothing about the signing identities. - The job does not wait for the checks. Nothing has been run on macOS, so a failing test should still leave a build to try. - One step checks the bundle: both architectures are in the executable and the signature verifies. No new dependency in the app. The job uses actions/upload-artifact v7, the current major version. The README says how to open the build. CLAUDE.md records that the host compiles and passes clippy for aarch64-apple-darwin, checked from Windows, and that the workflow itself has not run yet. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The first CI run built the macOS disk image and failed both check jobs, each for a reason of the runner's. - Windows: the checkout converted every file to CRLF and the Prettier check failed on all of them. A .gitattributes now sets LF for text files on every platform. No tracked file changes because of it. - macOS: the setup action installs stackql with Homebrew, which has v0.12.824, not the v1.0.888 release the tests were written against. Two agent tests failed on it. The check job now installs the release package on macOS, after checking its SHA-256. The README tells a tester to install the engine from the release package for the same reason. CLAUDE.md records what the first run showed on the macOS runner. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CI passes on both runners as of 27451dc. On the macOS runner that is lint, the 302 webview tests, clippy and 260 host tests against stackql v1.0.888 from the release package, and the bundle job's checks. The two agent tests that failed against Homebrew's v0.12.824 pass on the same runner with v1.0.888, which settles what was open in the last commit. The app itself has still not been opened on a Mac, and the keychain store there is still unconfirmed. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A click on a column header sorts the rows by that column: ascending, descending, then the order they arrived in. The engine sends every value as text, so the order is worked out from the text: numbers by size, words without regard to case and with the digits inside them by size, and empty values last in either direction. Rows that compare equal keep the order they arrived in. The grid draws the rows it is given and whoever owns the rows sorts them, so a cell reference and an export both mean the order on screen. The results pane now exports in that order. The grid can also widen its columns to fill the space it is in, until the operator drags one. The result tables in the conversation use that. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The host now writes a log of its own: one file for each run of the app, `stackql_workbench_<UTC time>.log` in `<app data dir>/logs`, one JSON object on each line. It is apart from the engine's audit log, which the engine writes to its own folder. The 20 newest files are kept. A turn's events are watched on their way to the webview. A tool call that the engine or the agent reports as failed is written with its tool, its statement or arguments, and what came back. So are notices, the end of each turn and a turn that failed. The engine coming up or failing to is logged too. Nothing is judged here: a call is logged as failed when the other side said so. This is the record for failed calls once the conversation stops listing them, which the next commits do. A record never holds an API key, an environment value or what the operator typed to the assistant. Help > Show Log File shows the current file in the file manager. The host holds the path, and the webview names nothing. No new dependency. Dates are worked out from the system clock by hand, to avoid one for a file name and a timestamp. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A model is now told what the operator sees: its answer, with the calls it made folded away as steps and the rows of its last statements as a table, and that a failed call is not shown, so it corrects one and carries on without describing the attempt. It is also told how to ask for a chart: a fenced block of the language `chart` holding one JSON object that names a chart type and columns. The text is in one place, `agent/guidance.rs`, and both ways a turn runs use it. The host's loop puts it in the system prompt, ahead of the engine's guidance, which still ends the prompt untouched. A delegated agent has its own system prompt, so it gets the text with the first message. This is about presentation, which is this app's to say because drawing is this app's capability. It says nothing about how a result is to be read. That stays the engine's, and a test holds the text to it. Each tool call event now carries the step of the model that asked for it, so that calls asked for together can be shown together. The host's loop knows each step. A delegated agent does not say where a step ends, so the calls that follow one of its messages count as one. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A chart block is one JSON object that names a chart type and columns: bar, line, area, pie, scatter or table. `lib/chart.ts` reads it as data and refuses what it does not understand. The rows come from the block, or from the most recent result set that has the columns it names. Values are read out of the text the engine sends, also `1,234` and `45%`. For a line, an area or a scatter chart, an x column of dates or numbers is placed where it falls, so a month with no rows leaves a gap. A chart never has more series than there are colours: past eight, the largest are kept and the rest are added together. What was left out is said in a note with the chart. `lib/chartLayout.ts` turns a model and a width into positions and paths: round axis values, bars at most 24 pixels thick with the free end rounded and a gap between neighbours, lines, areas, points and a ring. The eight series colours are tokens, with a second set for the dark theme. The first is a step of Classic Blue. The set was checked as a whole in each theme for separation under colour-blindness, and a test holds each colour to a floor against the surface. No charting dependency: these are pure functions, and the components that draw from them come next. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The conversation listed every tool call as a card, failed ones in red with the engine's error text. A turn that took a few attempts read as a page of errors with the answer at the bottom. A turn is now shown as its answer. What the assistant did on the way is one list of steps above it: each call with its SQL and result, and what the assistant wrote before going on to another call. The list is open while the turn runs and folds away when it ends. A call that failed is not listed and its error text is drawn nowhere. The model still gets the error exactly as the engine sent it, and the host writes it to the app's log. Two things stay visible: a call the operator was asked to approve, with its outcome, and a turn that failed as a whole. The result sets of the statements the assistant ran last are shown under the steps as tables. A table holds every row the host sent, sorts by a click on a column and saves as CSV through the save dialog. A chart block in a reply is drawn: bars, lines, areas, points or a ring, as SVG from this repository's own components, with a tooltip that reads every series at the position under the pointer and the table of the same rows one click away. A block that cannot be drawn is shown as the text it is, with the reason. Nothing a model writes becomes markup. The layout is worked out by pure functions in `lib/conversation.ts`. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
`docs/charts.md` describes the chart block, where its rows come from, the limits, the mark rules and the colours, how a turn is laid out, and what the app's log holds. `CLAUDE.md` and `README.md` are brought up to date: the status, what was run and what was not, the stack table, the layout, where the log is, how to build a copy that shares nothing with an installed one, and the UI notes for the conversation. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The host already added up input and output tokens over the calls of a turn. Two things made the numbers less than honest once they are shown. A provider that caches the prompt reads much of the input from its cache, and the count did not say so. Every backend now also reports the part of the input that was read from the cache: Anthropic's `cache_read_input_tokens`, Gemini's `cachedContentTokenCount`, `prompt_tokens_details.cached_tokens` from an OpenAI-compatible server, and the Copilot CLI's `cachedReadTokens`. Gemini counts the model's thinking apart from its reply and bills it as output. It was left out of the output count. It is now added, as is the tool-use prompt count on the input side. The API's own total is the sum of those parts. A count a provider does not send stays unknown and is not turned into zero. The end of a turn is written to the app's log with its counts. What the Copilot CLI sends was observed with one prompt to a probe: the answer to `session/prompt` carries `usage` for the whole turn. The test for the delegated agent now uses that shape. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
When a turn ends, the line that heads its steps says what it used: `6 steps 25,469 tokens in (12,631 cached), 158 out`. A turn with no steps says it on a line of its own in the same place, above the answer. It is small and to the side, because it is not part of the answer. The counts are the provider's own, added up over every call to the model in the turn. Nothing is estimated: a count that was not reported is left out, and a provider that reports none leaves the line out. Hovering the line says what the numbers are, and that each call to the model sends the conversation so far again. The host has sent these counts to the webview all along. The webview dropped them. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
`docs/spike-acp.md` gains what was observed on 19 November against the Copilot CLI 1.0.114: the answer to a prompt carries the turn's token counts, cached tokens are in the input count, and `usage_update` says how full the context window is, which is a different number. `docs/charts.md` says what the counts mean and where each backend's come from. `CLAUDE.md` and `README.md` say where they are shown, what was run, and that with Copilot the count is the size of a turn and not its cost. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The installers ship `stackql` with the Workbench, and that pair is the one built and tested together. The app now takes it as the default. The one thing that comes before it is a path the operator sets in Settings, which can only be done after the install. `STACKQL_BIN` used to come before the engine beside the app. It now comes after. A variable can be older than the install, and it would swap the engine without anyone having chosen that, or stop a fresh install from starting if it pointed nowhere. When the variable is set and passed over, the status says so and points at Settings. It is still strict when it is the source: with no installed engine, a variable that points nowhere is an error and not a reason to look further. What "installed with the app" means follows how each installer lays the pair out. - Windows: `stackql.exe` in the folder of the Workbench executable, where the MSI puts it. - macOS: for an app that runs from a bundle, an engine inside the bundle beside the executable, and failing that `/usr/local/bin/stackql`, where the PKG puts the command. The PKG puts none inside the bundle today. A build from this repository has no engine beside it and, on macOS, is not in a bundle, so there the variable is still the next thing tried. On Windows this was run with a build of the app and a copy of the engine in one folder: nothing set, the variable naming another engine, the variable pointing nowhere, a path in settings, both, and a path in settings that points nowhere. The macOS rule has unit tests only. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
`CLAUDE.md` gets the new order of the search, the decision behind it and what "installed with the app" means on each platform, with what was run. `README.md` says the same for whoever builds the MSI and the PKG: there is nothing for an installer to configure, and under `Program Files` the provider cache goes to the app data directory. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CI kept one thing to download, a Mac disk image for trying the app. The StackQL installers need two others, and neither was there. - `stackql-workbench-windows-x64`: the optimised Windows executable, from a new job. Until now CI only made a debug build on Windows and kept nothing. The job checks that the executable needs no library beside it in the installer's folder. - `stackql-workbench-macos-universal-app`: the Mac app bundle on its own, packed with tar so that the links and permissions inside it survive. Each comes with its SHA-256. Neither is signed for release: the StackQL release signs what it ships. The Mac app keeps the ad hoc signature it needs to run at all. These are workflow artifacts, which expire. How a build that ships is tagged and released is still to be decided, and the notes say so. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The executable ships on its own, beside stackql.exe, and has to need nothing from the system that could be missing. It was leaving the Universal C runtime to Windows: Tauri's default links the Visual C++ runtime in and not that one. Its import tables listed seven api-ms-win-crt libraries. The build now passes +crt-static on Windows, and Tauri's own handling is switched off in tauri.conf.json, because it would undo the flag for the Universal C runtime. The executable then asks the system for 19 libraries, all of them Windows itself. `scripts/check-exe-imports.js` reads the import tables of an executable and fails on a runtime library. CI runs it on the optimised build, in place of a search of the file for a few names. CI also checks with otool that the Mac app links only to what is part of macOS. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The window is drawn by the WebView2 runtime, which the executable cannot carry: it is a browser engine. Windows 11 has it built in and Windows 10 gets it with Edge, but it is still the system's to supply. An installer that must rely on nothing from the system can now ship it. When a `WebView2Runtime` folder with a runtime in it sits beside the executable, the app uses that one and does not look at what the system has. Otherwise it uses the system's, as before. The folder being there is the whole switch, so one executable serves both kinds of install. A folder with no runtime in it is ignored. Which runtime was used goes in the log. Run on Windows 11 with a copy of the installed runtime as the folder: the renderer process ran from the folder beside the app, and from the system's when the folder was absent or empty. Microsoft's Fixed Version package was not downloaded. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The host chooses a free port and then gives it to the engine. Something else can take the port in between, and the engine then exits at once with exit code 0. That was reported as a failed start. It happened in CI, where tests start engines side by side, as "The engine exited while starting (exit code 0)". The engine is now started again on a fresh port, up to three times, before the start is called a failure. An engine that is running and does not answer is not started again: another port would not make it answer. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
`README.md` says what each binary asks the system for, how CI checks it, and how an installer ships the WebView2 runtime beside the app when it must rely on nothing the system has, with what that costs. `CLAUDE.md` records the two build settings that go together, the renderer folder, the retry on a fresh port, what was run, and the decision that is still open: whether the MSI ships the runtime. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The maintainer said on 20 November 2026 that the binaries are to stay small and run on most modern Windows and Mac machines. So the WebView2 runtime is not shipped, and the app uses the one Windows has. `README.md` says what Microsoft states about where that runtime is, what the app shows where it is missing, and how an MSI can check for it and install it. `CLAUDE.md` records the decision, what was run, and two questions that are now open: whether the MSI installs a missing runtime, and the oldest macOS the app supports. What was run: the optimised build, with the loader pointed at an empty folder, showed Tauri's own dialog and exited when it was closed. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The maintainer decided on 20 November 2026 that the oldest macOS the app supports is 13. `bundle.macOS.minimumSystemVersion` is `13.0`, so the bundle declares it and an older macOS refuses to open the app. Until now the bundle declared Tauri's default of 10.13. The pages need the WebKit of Safari 16.4, and on a Mac the renderer is the one macOS has, so an older macOS would have opened the app and drawn it wrongly. CI checks that the bundle declares the version in `tauri.conf.json` and that both architectures of the executable are built for it. Also recorded, decided the same day: where the WebView2 runtime is missing, the MSI gives the operator the option to install it. That work is in the installer's repository. `README.md` has what it needs, with the address of Microsoft's bootstrapper as it answered today. A new open question: the StackQL MSI is built for x64 and arm64, and this repository builds the Windows executable for x64 only. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The StackQL MSI is built for x64 and for arm64, and this repository built the Windows executable for x64 only. The maintainer said on 20 November 2026 to build a native arm64 executable if emulation would not do. It would not: Windows emulates x64 only from Windows 11, there is no Arm machine here to try it on, and the arm64 MSI ships an engine built for Arm. - The checks run on GitHub's `windows-11-arm` runner as well, against the engine from `stackql_windows_arm64.zip` of the release, checked against its SHA-256. - The optimised build is made once for each processor, on a runner of that processor, and kept as `stackql-workbench-windows-x64` and `stackql-workbench-windows-arm64`. - `scripts/check-exe-imports.js` says which processor an executable is built for and, with one named, fails on another. A build on the wrong toolchain would otherwise pass for the right one. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The first run on GitHub's `windows-11-arm` runner passed: lint, the webview tests, clippy and the host tests against the engine from the release's arm64 archive, and the optimised build, which names arm64 as its processor and asks the system for the same 19 libraries as the x64 one. The app has not been opened on an Arm machine, and the x64 executable was not tried under emulation. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft, opened so that CI runs on the work so far. It is not a release.
What is in it
Everything built to date, which until now was only local:
README.mdhas the architecture and the roadmap.Conversation: answers, charts and tables
Added on 19 November, in the ten commits from
7553222tocf7f595. Before this, a turn listed every tool call as a card, failed ones in red with the engine's error text, and a request for a plot came back as a chart made of text characters.What changes for the operator:
stackql_workbench_<UTC time>.login<app data dir>/logs, apart from the engine's audit log. Help > Show Log File shows it. The Activity view still lists every statement with the engine's decision.1 step 25,469 tokens in (12,631 cached), 158 out. The counts cover every call to the model in the turn and are never estimated. With the Copilot CLI they say how large a turn was, not what it cost, since that plan is billed by the request.How a chart gets drawn: the model writes a fenced block of the language
chartholding one JSON object that names a chart type and columns. The rows come from the most recent result set that has those columns. The webview reads the block as data and draws SVG with components in this repository.docs/charts.mdhas the format, the limits and the mark rules.Choices made here that have not been reviewed yet:
agent/guidance.rs. It is about presentation only. It says nothing about how a result is to be read, which stays the engine's, and a test holds it to that.Which engine the app starts
Added on 19 November in
eaaded3, for shipping the Workbench in the StackQL MSI and PKG. The app now defaults to thestackqlit was installed with, since that pair is the one built and tested together. Only a path the operator sets under Settings comes before it.stackql.exein the folder of the Workbench executable, where the MSI puts it./usr/local/bin/stackql, where the PKG puts the command.STACKQL_BINused to come before the engine beside the app and now comes after. When it is set and passed over, the status bar says so. A build from this repository has no installed engine, so there the variable is still tried first.Neither installer has anything to configure for this. Two things to know when building them: under
Program Filesthe provider cache goes to the app data directory, so a first run lists no providers, and on an Intel Mac the app cannot tell the PKG's/usr/local/bin/stackqlfrom one linked there by a package manager.What the installers take
Added on 19 November, from
1b8c4bftoc1b5565. CI now keeps what the MSI and the PKG are built from, on every run.stackql-workbench-windows-x64stackql-workbench.exe, the optimised build for x64, with its SHA-256stackql-workbench-windows-arm64stackql-workbench.exe, the optimised build for Arm, with its SHA-256stackql-workbench-macos-universal-app.tar.gz, with its SHA-256Neither is signed for release. The StackQL release signs what it ships.
Both are built to need nothing from the system that has to be installed, and CI checks it.
scripts/check-exe-imports.jsreads the import tables and fails on a runtime library./usr/lib, checked withotool.stackql-windows-installerrepository and is not done yet. AWebView2Runtimefolder beside the app is still used when there is one.A fix came with this: the engine is started again on a fresh port when it exits at once, which is what happens when something takes the port between it being chosen and bound. That was the cause of one failed check on Windows.
Workflow artifacts expire after 90 days. A build that ships should come from a tagged release, which this repository does not make yet.
The macOS test build
The
Bundle (macOS, universal)job builds the app for Apple Silicon and Intel and keeps the disk image as the artifactstackql-workbench-macos-universal, on the run's summary page. The signature is ad hoc and nothing is notarised, so macOS has to be told to open it. The README section "Test build for macOS" says how.What has been run
stackqlv1.0.888. For the conversation work: lint, type check and 462 webview tests, andcargo fmt, clippy and the host tests (270 unit, 10 agent integration, 13 engine integration).claude-haiku-4.5. In the first the model wrote a chart block from the guidance on its first try. In the second three of its calls failed on the way: none was listed, and all three were in the log.stackql.exein one folder, under six conditions: nothing set,STACKQL_BINnaming another engine,STACKQL_BINpointing nowhere, a path in settings, both, and a path in settings that points nowhere. The folder was a writable one, so the data folder fallback underProgram Fileswas not part of it. The macOS rule has unit tests only.WebView2Runtimefolder when there was one, and the system's again when that folder held no runtime. The runtime in the folder was a copy of the installed one, not Microsoft's Fixed Version package. No machine without WebView2 was tried, and no freshly installed Windows 11. A machine without it was imitated by pointing the loader at an empty folder: the optimised build showed the dialog and exited.windows-11-armrunner, againststackqlv1.0.888 from the release's arm64 archive. Lint, the webview tests, clippy and the host tests pass there, the integration tests that start a real engine among them. The app has not been opened on an Arm machine, and the x64 executable was not tried under emulation.Not run: Help > Show Log File has not been clicked, since it opens a window on the desktop. No API key backend has drawn a chart from a real model.
Generated with Claude Code